Syncs

Syncs let you continuously sync data from external APIs. They work with any data the external API exposes.

​

When should you use syncs?

• You want to store a copy of the external API’s data in your app and keep this copy up to date
• You want to know when data in the external API changes, but the API offers no webhooks for this
• You want to combine polling syncs and webhooks to get a reliable, real-time stream of changes from the external API

Common examples:

• Syncing contacts, companies, or deals from a CRM (HubSpot, Salesforce, Attio, etc.)
• Syncing files from drives (Google Drive, SharePoint, Box, etc.)
• Syncing call transcripts from video recorders (Gong, Fathom, Zoom, etc.)

You can also implement two-way syncs by combining syncs with Actions.

​

Key facts

• Syncs run in Nango’s infrastructure, powered by Functions
  • You control the code of the sync: which data to fetch, transformations, data models, etc.
  • All platform features, like data validation, per-customer config, retries, and rate-limit handling, are available for syncs
• Syncs are defined once and run in the context of each Connection (API key or access token of your user)
• Syncs can be incremental (only fetch changed data) or full refresh (always fetch all data)
• Synced data is cached in Nango (encrypted at rest and in transit)
• Nango detects changes to synced data (additions, updates, and deletes) and sends a webhook to your app
• You set the frequency at which the sync polls for new data (15 seconds minimum interval)
• Syncs handle rate limits, retries, and pagination
• All sync runs and API requests are logged in Nango’s logs
• Data retention: Records not updated for 30 days have their payload emptied; syncs not executed for 60 days have all records deleted (learn more)

​

How syncs work

Syncs are defined on the integration (e.g., GitHub, Google Drive, etc.) by implementing a Function with the sync’s logic. Nango then executes the sync for each Connection of this integration. This lets you customize the sync’s logic, execution frequency, etc., for each customer, if necessary. Follow our implement a sync guide for step-by-step instructions to create your own syncs.

​

Syncs in detail

​

Incremental vs. full-refresh syncs

Syncs can either be incremental or full-refresh. Nango supports both and automatically detects changes to records in both modes. Incremental sync These only fetch data that has changed since the last execution, appending it to the existing dataset. This mode is more efficient for larger datasets and relies on the external API’s support for querying modified records. Unfortunately, not all APIs and not all endpoints support this. Full refresh sync These syncs retrieve the entire dataset during each execution. They take longer to execute, especially for large datasets. Often used as a fallback if the external API endpoint offers no way to filter or sort records by last modified date. Refer to the implement a sync guide for more information on how to implement either in Nango.

​

Deletion detection

Nango supports detecting deleted records on external APIs. Deletion detection for incremental syncs requires specific support for this by the external API. For full-refresh syncs, deletes can always be detected. Follow our implementation guide for deletion detection in syncs to implement this in your own syncs.

​

Real-time syncs with webhooks

Nango supports real-time syncs with webhooks. You can either rely entirely on webhooks for the sync or combine webhooks with polling sync runs to ensure you never miss data. Follow our implement real-time syncs with webhooks guide to add real-time support for your sync.

​

Data retention policies

Nango automatically manages data retention for synced records to ensure compliance with modern data security standards: Automated payload pruning (30 days) Records that haven’t been updated for 30 days will have their payload automatically pruned. The record metadata (including record ID and payload hash) remains intact for change detection purposes. After pruning, the record’s data fields are no longer retrievable from the Nango cache, but Nango can still track the record and detect future changes. Automated hard deletion (60 days) If a sync hasn’t executed for 60 days, all records belonging to that sync will be permanently deleted. Best practice: Fetch records from Nango promptly after receiving webhook notifications and store them in your own system. Don’t use Nango’s cache as your primary long-term data store. Learn more about data retention policies